*************************************************************
*** History of SOFA Toolbox for Matlab and Octave
*** Acoustics Research Institute, Austrian Academy of Sciences, Vienna
*** Project leader: Piotr Majdak, piotr.majdak@oeaw.ac.at
*** Contributors:
***		Michael Mihocic
***		Harald Ziegelwanger
***		Hagen Wierstorf
***		Wolfgang Hrauda
***		Fabian Brinkmann
***		Felix Perchfler
*************************************************************

*** DEVELOPMENT STATUS ***

*** v2.2.0 (master branch)
- version numbers fixed, branche merged with development branch
- new supported data type: Audio (used in AnnotatedEmitterAudio, AnnotatedReceiverAudio)

*** v2.1.5 (development branch)
- SOFAupgradeConventions.m:
	- upgrade from SingleRoomDRIR files to SingleRoomSRIR implemented
	- upgrade from MultiSpeakerBRIR files to SingleRoomSRIR implemented
	- outdated version of FreeFieldDirectivityTF_1.0.csv removed (FreeFieldDirectivityTF_1.1.csv is up-to-date)
- SOFAcompileConventions: bug fix on compiling conventions only if CSV newer than MAT files
- demos:
	- demo_MultiSpeakerBRIR.m added; loading SOFA without checks, source convention outdated
	- demo_SingleRoomDRIR.m added; loading SOFA without checks, source convention outdated
	- demo_UMA2SOFA.m added
	- demo_FreeFieldDirectivityTF: check for AK tools improved, link updated
- converter added:
	- SOFAconvertUMA2SOFA.m
- test_SOFAall.m adapted to new demos
- SOFAsave: help text added about supressing the API warnings
- SOFAhrtf2dtf: warning if Data.Delay >0; instead of crashing
- Conventions:
	- SingleTrackedAudio_0.1 added
	- SingleTrackedAudio removed again, replaced by conventions:
		- AnnotatedEmitterAudio_0.1
		- AnnotatedReceiverAudio_0.1

*** v2.1.4 (master branch)
- version numbers fixed, branche merged with development branch
- minor update in SOFAgetVersion

*** v2.1.3 (development branch)
- converters added (test folder):
	- SOFAconvertMultiSpeakerBRIR2SingleRoomMIMOSRIR
	- SOFAconvertSingleRoomDRIR2SingleRoomSRIR
- test_SOFAdbURL: script improved; bugs fixed for sofa files creating more than one warning
- SOFAplotHRTF:
	- bugfix: changed ITDhorizontal to plot absolute ITD values
	- extended functionality: option to select ITD estimator

*** v2.1.2 (master branch)
- version numbers fixed, branche merged with development version v2.1.1
- minor update in SOFAgetVersion

*** v2.1.1 (development branch)
- fixes for some version numbers

*** v2.1 (first 2.x release)
- conventions (csv files) updated to v2.1; several bugs fixed, version numbers and content adapted to standard
- SOFAgetConventions: returns only the mandatory metadata per default. 

*** v2.0 (not released, rebranded to SOFA Toolbox)

## Rebranding ##
- main directory renamed to "SOFAtoolbox"
- repository renamed to "SOFAtoolbox"
- subfolder "HRTFs" renamed to "data"; some files adapted
- all SOFA files created by demo_ will be saved in sofatoolbox\test

## Core Functionality ##
- .gitignore added, updated multiple times
- support for spherical harmonics added
- SOFAconvertCoordinates.m: type horizontal-polar removed (not (properly) defined in SOFA)
- SOFAarghelper: minor bugs fixed (changes FB); license changed from GPL to EUPL, in agreement with Peter L. Soendergaard
- SOFAinfo: showing all global mandatory fields now, plus some more for SimpleFreeFieldHRIR
- Readme.md: Example fixed (demoPlaySound.m)
- headers of functions checked, updated, author format changed to machine-readable format (#author)
- NETCDFload: 'deblank' command added when loading strings to avoid trailing empty spaces in size of array dimension
- NETCDFsave: error handling improved when no file handle available
- SOFAcalculateITD.m added, adapted from AMT itdestimator
- SOFAcalculateLFE.m added (by DC), db changed to mag2db (Octave support)
- SOFAstart: 
	- bug fixed when using 'restart' option: SOFAdbPath and SOFAdbURL were not reset
	- bug in help comment fixed
	- flag 'full' added: show all information, including all compiled conventions & versions
	- changed order of display output messages ((c) first)
	- bug fixed when adding paths (added at bottom in some specific cases)
- SOFAcheckFilename: fix for strings instead of characters, fix for file names shorter than 7 characters
- SOFAremoveVariable: remove not only variable, its dimension, but also its attributes; bug fixed for Octave
- SOFAconvertConventions: rmfield replaced by SOFAremoveVariable for non data variables -> improved stability
- SOFAload: The convention's version will not be updated automatically anymore when loading a SOFA file
- SOFAsave: The convention's version will not be updated when saving a SOFA file; a matching csv file with convention+version must be existing, otherwise an error is thrown
- SOFAresample.m added (resample SOFA file)

## Toolbox Functionality
- conventions:
	- conventions for SOFA 2.0 added
	- SOFAgetConventions: Versioning of convention files .CSV added
	- csv files renamed to always include SOFAConventionsVersion in file name (created .mat files are unaffected)
	- FreeFieldDirectivityTF_1.0.csv: 
		- updated by David Ackermann (not sure if ReceiverPosition and EmitterPosition still need to be updated)
		- mandatory flag removed for: Global:Comment, ListenerUp, ListenerUp:Type, ListenerUp:Units
		- dimension of ReceiverPosition and EmitterDescription fixed
	- FreeFieldHRTF_1.0.csv: GLOBAL:SOFAConventionsVersion version number fixed
	- SingleRoomSRIR_1.0.csv: GLOBAL:SOFAConventionsVersion version number fixed, RoomCornerA, RoomCornerB, RoomCorners:Type, RoomCorners:Units: Mandatory flag removed
	- Dimension of Data.SamplingRate fixed to "I, M" for: GeneralFIR-E_2.0.csv, GeneralFIR_2.0.csv, General_1.0.csv, SimpleFreeFieldHRIR_1.0.csv, SimpleFreeFieldHRSOS_1.0.csv, SimpleHeadphoneIR_1.0.csv, SingleRoomSRIR_1.0.csv
	- Conventions2Wiki.m: Column headers flags and dimensions changed to a hyperlink linking to that corresponding part on the website
	- several bugs fixed; non-ASCII quotes replaced by ' (changes FB)
	- convention FreeFieldHRIR_1.0.csv added
	- SOFAcompileConventions:
		- ignores files beginning with '_'
		- bug fixed when running in Octave
		- '10' replaced by 'newline' in strings to avoid warnings in Octave
		- display messages changed to output variable dispOutput
	- bug fixed: replaced version "2" by "2.0" to keep one minor digit everywhere
	- flags fixed
	- GeneralSOS_1.0.csv: bug fixed (version number in file)
- demos:	
	- demoPlaySound.m added
	- demo_FreeFieldHRTF.m added; updated several times, allows saving figures as fig & png (see parameter 'savefigures'), some bug fixes
	- demo_FreeFieldDirectivityTF.m: adapted to actual data on sofaconventions.org -> working now; plot_trumpet_directivity included
	- SOFAconvertMIT2SOFA.m, demo_FHK2SOFA.m, demo_SingleRoomDRIROldenburg.m, demo_SingleRoomMIMOSRIR.m, demo_TUBerlin2SOFA.m: error message if source files are not available
	- demo_ARI2SOFA.m, demo_LISTEN2SOFA.m: bug fixed: subject_ID was always overwritten; error message if source files are not available
	- demo_SimpleFreeFieldHRIR2TF.m: bug fixed: Object to be saved was wrong; error message if source files are not available; updated several times; parameter 'plotfigures' causes plotting all figures, and saving them (fig, png) if set to 1
	- demo_SimpleHeadphoneIR.m: if .MeasurementDate is not existing use .GLOBAL_DateCreated as measurement time (legend in figure)
	- SOFAconvertSCUT2SOFA.m: bug fixed when source files are not available -> error message
	- demo_BTDEI2SOFA.m: Minor bug fixed in error message text
	- demo_SOFAcalculateITD.m added
	- demo_SOFAcalculateLFE.m added (by DC)
	- demo_SphericalHarmonicsMic added
	- demo_MultiSpeakerBRIR.m and demo_SingleRoomDRIROldenburg.m removed (outdated)
	- demo_GeneralSOS.m added
	- updates, fixes in demos files and test_SOFAall.m
	- demo_SOFAresample.m added
- test_SOFAall.m: 
	- structured (first *->SOFA, then SOFA->*, then SOFA functions, then SOFA conventions), and sorted (alphabetically)
	- missing demos added
	- displayed messages improved
	- figures show demo functions' names headers
	- some bugs fixed; all conventions are included in at least one demo file; all demos are tested with Matlab & Octave (run test_SOFAall.m)
		- Matlab: all demos are working in Matlab, without any visible warnings
		- Octave: all demos are working without a few exceptions (not working at all; skipped in Octave), and some minor restrictions cause by unsupported commands, see warning messages during process for details
	- some bugs fixed; demos that require souce files that are not publicly available will be catched with a warning instead of an error
- test_SOFAdbURL.m: 
	- new test function added, to download, load and save all files from SOFAdbURL link
	- a log files with all errors and warnings is created
- download links updated for:
	- HRTFs\ARI\readme.txt
	- HRTFs\CIPIC\readme.txt
	- HRTFs\TU-Berlin KEMAR\readme.txt	
- SOFAplotHRTF: 
	- 'convert' flag added -> 1: convert to FIR and then to TF domain. Can be set to 0 if data is available in TF domain (FreeFieldDirectivityTF, GeneralTF, SimpleFreeFieldHRTF conventions). By default the function chooses the best option.
	- type 'ITDhorizontal' added (changes DC)
	- Octave support (except for type itdhorizontal)
	- dependency on function 'npi2pi' removed (required toolbox in Matlab; in Octave not supported; outdated anyway)
	- keyvalue 'R'/'r' renamed to 'receiver'
	- Obj.GLOBAL_Title only displayed in figure title if not empty; title handling improved
	- input flags for normalization renamed to: 'normalization','nonormalization'
	- input flags for conversion to IR domain renamed to: 'conversion2ir','noconversion2ir'
- SOFAplotGeometry:
	- bug fixed when extracting LU (listener up) coordinates
	- minor bugs fixed
- headers of functions checked, updated, author format changed to machine-readable format (#author)
- helper folder renamed to helpers; folder is prepared for downloadable third-party functions
- helper functions removed; some functions are already supported by MATLAB, a few functionalities were implemented in the files themselves
- isoctave.m removed, replaced by code in files
- miro.m removed from repository; class file is downloaded if needed (by demo_FHK2SOFA, SOFAconvertFHK2SOFA, SOFAconvertTHK2SOFA); file might also be included in other toolboxes and can be used from them

## TO-DO ##
- SOFAplotGeometry: complete rewrite with extensive support
- SOFAplotGeometry shows a cloud for spatially continuous emitters and receivers


************************************************************************************************************


*** v1.1.2
- SOFAplotGeometry: bug fix if no SourceView given
- FreeFieldDirectivityTF: missing eCM in EmitterPosition fixed
- SOFAcheckFilename: do not convert if filename is http://
- SOFAplotHRTF: plot TF with regular frequency grid. Not tested for irregular grids, though...

*** v1.1.1
- SOFAstart: bug fix when starting for the first time
- SOFAconvertTUBerlinBRIR2SOFA.m: bug fixed in Obj.ReceiverPosition: left / right was inverted 
- SOFAconvertTHK2SOFA.m: bug fixed in Obj.ReceiverPosition: left / right was inverted 
- SOFAconvertFHK2SOFA.m: bug fixed in Obj.ReceiverPosition: left / right was inverted 
- SOFAappendText.m: example added to help
- SOFAcompileConventions: fix for changes in Octave 4.2
- FreeFieldDirectivityTF: updated to version 0.2

*** v1.1.0 (not released)
- SOFAremoveVariable added. It removes a variable from the SOFA object.
- SOFAplotGeometry: show SourceView, and bug fix ListenerView. 
- SOFAdbPath, SOFAdbURL: reset the path/URL to the default if the parameter is 'reset'.
- SOFAhrtf2dtf: handling for R=1 added.
- SOFAfind added: Find an index for a given position (draft, to be improved).
- SOFAload: provide error message on loading unknown conventions

*** v1.0.4 (29.4.2019)
- on "SOFA upgrade warning", display a message on how to switch it off
- SOFAplotHRTF: 'magsagittal' added to plot HRTFs along a sagittal plane.
- SOFAload can use filenames beginning with "db://" to indicate to load from the database (local or remote)
- SOFAstart avoids repeated starts now - 
  - once SOFAstart has been started, SOFAstart won't be executed fully again, when the paths are still available.
  - Call SOFAstart('restart') if a restart needs to be forced. 
  

*** v1.0.3 (5.9.2018)
- automatic load of the netcdf package in Octave on SOFAstart
- SOFAspat: bugs in normalization, actual position selection removed
- SOFAhrtf2dtf: RMS and weighted averaging added, Octave compatibility ensured
- SOFAcompileConventions: bug fix when compiling conventions in Octave 4.2.1
- test_SOFAall: suppress irrelevant warnings
- SOFAconvertMIT2SOFA: wavread replaced by audioread
- SOFAconvertConventions: it can convert from SimpleFreeFieldTF to SimpleFreeFieldHRIR. 
- SOFAplotHRTF: more variable input of parameters, normalization optional
- SOFAconvertTHK2SOFA: converter from THK format (in miro format) to SOFA added. 

*** v1.0.2 (16.8.2016)
- SOFAplotHRTF: extended to SimpleFreeFieldTF and some cases of GeneralTF
- SOFAplotGeometry: extended to SimpleFreeFieldTF
- SOFAconvertTUBerling2SOFA: uses MultiSpeakerBRIR now
- SOFAspat, SOFAcalculateAPV: minor bug fixes

*** v1.0.1 (10.6.2015)
- miro class is not supported in Octave. Error is thrown in demo_FHK2SOFA and converterFHK2SOFA
- demo_BTDEI2SOFA: bug fix in renamed BTDEI files
- demo_SOFA2ARI: bug fix in coordinate comparison

*** v1.0.0 (3.6.2015)
- 'short' flag added to SOFAstart in order to show only a short header on start-up.
- warnings are function-specific now and can be specifically enabled/disabled.

*** v0.9.1 (13.5.2015) 
- 0.9.1 is the internal numbering for the release version 1.0 RC2
- SimpleFreeFieldSOS added
- SOFAexpand and SOFAaddVariable handle Data. variables now
- SOFAplotHRTF supports SimpleFreeFielsSOS now

*** v0.9.0 (12.5.2015) 

- 0.9.0 is the internal numbering for the release version 1.0 RC1
- update of all conventions to SOFA 1.0
- changes according to the AES212-standard implemented
- Octave: upgraded to a new netcdf-package: http://modb.oce.ulg.ac.be/mediawiki/index.php/Octave-netcdf
- Matlab/Octave: NETCDF* functions merged for both systems (thx to Hagen Wierstorf)
- HRTFs directory: database handling improved: 
  - SOFAdbPath mirrors http://sofacoustics.org/data now. 
	- Warning: directory structure of HRTFs/SOFA changed! 
	- all SOFA files created by demo_ will be saved in sofa_api_mo_test 
	- all demo_ files which use SOFA files will be automatically downloaded from sofacoustics.org
- clean up of comments
- SOFAcalculateAPV: reimplemented
- horsph and sph2hor: bug fixes
- directory CDL deleted (had historical relevance only)
- SOFAdefinitions: flag 'units' added for unit aliases.
- SOFAgetConventions: returns empty vector if conventions not supported

*** v0.4.4 (until 20.4.2015) unreleased

*** v0.4.3 (5.6.2014) by Piotr Majdak
- fix: annoying bug in SOFAupgradeConventions

*** v0.4.2 (7.4.2014) by Piotr Majdak
- fix: SOFAhrtf2dtf supports more than two receivers

*** v0.4.1 (30.3.2014) by Piotr Majdak
- MultiSpeakerBRIR conventions added
- SOFAcompact: compacts variables along dimensions, opposite to SOFAexpand. Functionality not complete for 3D variables
- SOFAcompare: compares two SOFA objects. Preliminary functionality; compares attributes only
- SOFAexpand: expanding of Data added
- bug fix: SOFAplotGeometry
- function-specific warnings added: SOFA:upgrade and SOFA:save
- SOFAload optimized for handling huge (3.7 GB) data files on a 4 GB RAM machine


*** v0.4 (19.3.2014) by Piotr Majdak
- implements SOFA 0.6:
  - GLOBAL_Source renamed to GLOBAL_Origin 
  - GLOBAL_TimeCreated and GLOBAL_TimeModified renamed to GLOBAL_DateCreated and GLOBAL_DateModified, respectively
  - If ListenerUp is provided, ListenerView must be provided as well. If ListenerView is provided, ListenerView_Type and ListenerView_Units must be provided as well. This also applies to Source, Emitter, and Receiver objects. 
  - Geometry: only "cartesian" or "spherical" coordinate systems allowed
  - In SimpleFreeFieldHRIR: GLOBAL_SubjectID renamed to GLOBAL_ListenerShortName
- Converters adapted to provide more precise information
- SOFAappendText added for appending a text to an attribute
- SOFAdefinitions: returns various definitions, depending on the input flag
- SOFAupgradeConventions: upgrades conventions up to 0.6 now. 

*** v0.3.1 (2.9.2013) by Piotr Majdak
- zip file required 7-zip, fixed
- minor bug fixes

*** v0.3.0 (27.8.2013) by Piotr Majdak
- major change: .API added to the structure, contains .Dimensions and the dimension sizes (formely known as .DimSize)
- implements SOFA 0.5 (without the support for string arrays)
- upgrade of SimpleFreeFieldHRIR 0.3 and other conventions
- syntax of convention files .csv adapted to that from the specs ("_" replaced by ":")
- SOFAcalculateAPV added, provides calculation of the apparent position vector (APV)
- SOFAplotGeometry added, rudimentary plotting available for SimpleFreeFieldHRIR and SingleRoomDRIR
- SOFAaddVariables supports private variables now

*** v0.2.9 (30.5.2013) by Piotr Majdak
- development snapshot for the draft of SOFA 0.4 
- tested for Matlab (Octave support not finished yet)
- conventions implemented as CSV files which are compiled to MAT at start and are cached by SOFAgetConventions
- user-defined HRTF database path
- seemless download of remote SOFA files on SOFAload
- user-defined HRTF internet repository
- seemless upgrade from SOFA 0.3 files on SOFAload

*** v0.2.1 (13.5.2013) by Piotr Majdak
- Bug fix with the wrong spelling of "License"
- "License" it very restrictive per default now
- demo_SOFAsave included

*** v0.2.0 (2.5.2013) by Piotr Majdak
- Updated to SOFA 0.3
- Octave support added
- demo_* create file names compliant with MS DOS FAT character set
- test script (test/test_SOFAall.m) added
- converters do not add database specific attriubutes, this is done in demo_*
- new demos: SOFAmerge, SOFAload, SOFAsave
- readme improved
- Pulse.sofa removed as binary, it can be created with demo_SOFAsave now
- Link to HRTF files saved as SOFA added (nice for playing around)

*** v0.1.4 (2.5.2013) by Piotr Majdak
- Major bug fix: dimension order reversed while loading/saving in Matlab
- Some other minor issues closed
- Ready for intercompatibility test between Matlab and Octave

*** v0.1.3 (18.4.2013) by Piotr Majdak
- This version implements SOFA specs version 0.2 with the following limitations:
  - no Octave support
  - only SimpleFreeFieldHRIR supported and tested
  
- Detailed changes:  
  - directory structure changed
  - new converter added: SOFA2ARI
  - SOFAdbPath added

*** v0.1.2 (17.4.2013) by Piotr Majdak
- SOFAload: partial loading added. Load of metadata only or by measurement section
- docs: changes since AES2013-specs added.
- history file moved to docs
- Repository cleaned from older stuff

*** v0.1.1 (16.4.2013) by Piotr Majdak
- SOFAload improved: checks added. Still further checks would be nice, but it can be used now.
- SOFAsave improved: saves user-defined variables
- SOFAexpand added: expands the singleton dimensions in the SOFA object
- Convertors for MIT KEMAR, LISTEN, and CIPIC databases added (with corresponding demos)
- HRTF directory created where all HRTFs should be stored. The convertors rely on that.
- SOFAspat improved, now the engine works better

*** v0.1.0 (11.4.2013) by Piotr Majdak
- Saving/Loading works in Matlab, it is quite rudimentary now:
  - Data and Variables saved as Double
  - No string in variables supported yet
  - One Conventions implemented and tested (SingleFreeFieldHRIR)
  - Loading: no checks (todo)
  - Saving: removes optional variables (bug)
  - No partial loading/saving yet 
- Convertion: ARI2SOFA with demo_ARI2SOFA added
- Spatialization: very rudimentary demo added (SOFAspat and demo_SOFAspat), just for fun

*** v0.0.12 (12.3.2013) by Piotr Majdak
- Conventions: transmitter renamed to emitter

*** v0.0.11 (7.3.2013) by Piotr Majdak
- Conventions added
- Octave branch deleted
- Examples: ARI2SOFA as a function
- General: adapted to current specs. Don't use yet.

*** v0.0.10 (5.3.2013) by Piotr Majdak
- ARI2SOFA: changed to a function now, the fields are more clear defined
- SOFAsave: transmitted and receiver separated, dimensions changed
- Specs have drastically changed - beware of using this version at the current development state

*** v0.0.9 (31.1.2013) by Piotr Majdak
- included octave part from Hagen Wierstorf
- changed the data structure format
- added try-catch to SOFAsave to avoid open file handles

*** v0.0.8 (24.08.2012) by Wolfgang Hrauda
- changed data structure format
- updates and fixes in several functions and scripts
- added Eigenmike.sofa as a demo file

*** v0.0.7 (23.08.2012) by Wolfgang Hrauda
- now using structures or cells as input and output values of functions
- added and renamed several functions and scripts
- updates in several functions and scripts

*** v0.0.6 (14.08.2012) by Wolfgang Hrauda
- added new functions for coordinate type conversion
- functionality of SOFAgetData slightly expanded
- dismissed function SOFAloadVariables (is now an option in SOFAload)
- "ARI_to_SOFA_lab_setup" updated
- minor fixes in several functions

*** v0.0.5 (08.08.2012) by Wolfgang Hrauda
- implemented additional dimensions for string variables in SOFAsave
- added new function SOFAloadVariables (a variant of SOFAload)
- added new demo script "ARI_to_SOFA_lab_setup"
- fixes in several functions

*** v0.0.4 (07.08.2012) by Wolfgang Hrauda
- fixed some issues in SOFAsave
- minor changes in SOFAload
- added new functions SOFAgetID, SOFAgetData, SOFAlistVariables

*** v0.0.3 (03.08.2012) by Wolfgang Hrauda
- split demo script in two API functions and one script that calls them
- change file extension to 'sofa'

*** v0.0.2 (01.08.2012) by Wolfgang Hrauda
- finished matrix dimension check

*** v0.0.1 (31.07.2012) by Wolfgang Hrauda
- demo script that loads ARI .mat file, converts it to SOFA format and writes to .nc-file
  then reads all data from .nc.file
